home *** CD-ROM | disk | FTP | other *** search
/ SGI Hot Mix 17 / Hot Mix 17.iso / HM17_SGI / research / lib / cw_tmpl.pro < prev    next >
Text File  |  1997-07-08  |  6KB  |  189 lines
  1. ; $Id: cw_tmpl.pro,v 1.3 1997/01/15 03:11:50 ali Exp $
  2. ;
  3. ; Copyright (c) 1992-1997, Research Systems, Inc.  All rights reserved.
  4. ;    Unauthorized reproduction prohibited.
  5. ;+
  6. ; NAME:
  7. ;
  8. ; PURPOSE:
  9. ;
  10. ; CATEGORY:
  11. ;    Compound widgets.
  12. ;
  13. ; CALLING SEQUENCE:
  14. ;    widget = CW_TMPL(parent)
  15. ;
  16. ; INPUTS:
  17. ;       PARENT - The ID of the parent widget.
  18. ;
  19. ; KEYWORD PARAMETERS:
  20. ;    UVALUE - Supplies the user value for the widget.
  21. ;
  22. ; OUTPUTS:
  23. ;       The ID of the created widget is returned.
  24. ;
  25. ; COMMON BLOCKS:
  26. ;    None.
  27. ;
  28. ; SIDE EFFECTS:
  29. ;
  30. ; PROCEDURE:
  31. ;    WIDGET_CONTROL, id, SET_VALUE=value can be used to change the
  32. ;        current value displayed by the widget.
  33. ;
  34. ;    WIDGET_CONTROL, id, GET_VALUE=var can be used to obtain the current
  35. ;        value displayed by the widget.
  36. ;
  37. ; MODIFICATION HISTORY:
  38. ;-
  39.  
  40.  
  41. PRO tmpl_set_value, id, value
  42.  
  43.     ; This routine is used by WIDGET_CONTROL to set the value for
  44.     ; your compound widget.  It accepts one variable.  
  45.     ; You can organize the variable as you would like.  If you have
  46.     ; more than one setting, you may want to use a structure that
  47.     ; the user would need to build and then pass in using 
  48.     ; WIDGET_CONTROL, compoundid, SET_VALUE = structure.
  49.  
  50.     ; Return to caller.
  51.   ON_ERROR, 2
  52.  
  53.     ; Retrieve the state.
  54.   stash = WIDGET_INFO(id, /CHILD)
  55.   WIDGET_CONTROL, stash, GET_UVALUE=state, /NO_COPY
  56.  
  57.     ; Set the value here.
  58.  
  59.     ; Restore the state.
  60.   WIDGET_CONTROL, stash, SET_UVALUE=state, /NO_COPY
  61.  
  62. END
  63.  
  64.  
  65.  
  66. FUNCTION tmpl_get_value, id
  67.  
  68.     ; This routine is by WIDGET_CONTROL to get the value from 
  69.     ; your compound widget.  As with the set_value equivalent,
  70.     ; you can only pass one value here so you may need to load
  71.     ; the value by using a structure or array.
  72.  
  73.     ; Return to caller.
  74.   ON_ERROR, 2
  75.  
  76.     ; Retrieve the structure from the child that contains the sub ids.
  77.   stash = WIDGET_INFO(id, /CHILD)
  78.   WIDGET_CONTROL, stash, GET_UVALUE=state, /NO_COPY
  79.  
  80.     ; Get the value here
  81.  
  82.  
  83.     ; Restore the state.
  84.   WIDGET_CONTROL, stash, SET_UVALUE=state, /NO_COPY
  85.  
  86.         ; Return the value here.
  87.  
  88. END
  89.  
  90. ;-----------------------------------------------------------------------------
  91.  
  92. FUNCTION tmpl_event, ev
  93.  
  94.     ; This routine handles all the events that happen in your
  95.     ; compound widget and if the events need to be passed along
  96.     ; this routine should return the new event.  If nobody needs
  97.     ; to know about the event that just occured, this routine 
  98.     ; can just return 0.  If your routine never needs to pass
  99.     ; along an event, this routine can be a procedure instead
  100.     ; of a function.  Whichever type used must be set below in the
  101.     ; WIDGET_BASE call using either the EVENT_PROC or EVENT_FUNC 
  102.     ; keyword.  An event function that returns a scalar 0 is 
  103.     ; essentially an event procedure.
  104.  
  105.   parent=ev.handler
  106.  
  107.  
  108.     ; Retrieve the structure from the child that contains the sub ids.
  109.   stash = WIDGET_INFO(parent, /CHILD)
  110.   WIDGET_CONTROL, stash, GET_UVALUE=state, /NO_COPY
  111.  
  112.     ; Process your compound widgets events here.
  113.     ; If the event doesn't need to propagate up any further, just 
  114.     ; return 0 and the event will stop here.  Otherwise, modify
  115.     ; the event for your usage and return it.
  116.  
  117.  
  118.         ; Restore the state structure
  119.   WIDGET_CONTROL, stash, SET_UVALUE=state, /NO_COPY
  120.  
  121.     ; You may need to add more tags to the event structure for your 
  122.     ; compound widget.  If so do it after the first three which are
  123.     ; required and preserve the order of the first three.
  124.  
  125.   RETURN, { ID:parent, TOP:ev.top, HANDLER:0L }
  126. END
  127.  
  128. ;-----------------------------------------------------------------------------
  129.  
  130. FUNCTION cw_tmpl, parent, UVALUE = uval
  131.  
  132.     ; You should not use the user value of the main base for
  133.     ; your compound widget as the person using your compound widget
  134.     ; may want it for his or her own use.  
  135.     ; You also should not use the user value of the first widget you
  136.     ; install in the base as it is used to keep track of the state.
  137.  
  138.     ; state structure for your compound widget.
  139.  
  140.   IF (N_PARAMS() EQ 0) THEN MESSAGE, 'Must specify a parent for Cw_Tmpl'
  141.  
  142.   ON_ERROR, 2                    ;return to caller
  143.  
  144.     ; Defaults for keywords
  145.   IF NOT (KEYWORD_SET(uval))  THEN uval = 0
  146.  
  147.     ; Rather than use a common block to store the widget IDs of the 
  148.     ; widgets in your compound widget, put them into this structure so
  149.     ; that you can have multiple instances of your compound widget.
  150.   state = { id:0 }
  151.  
  152.     ; Here the widget base that encompasses your compound widget's 
  153.     ; individual components is created.  This is the widget ID that
  154.     ; is passed back to the user to represent the entire compound
  155.     ; widget.  If it gets mapped, unmapped, sensitized or otherwise
  156.     ; effected, each of its individual subcomponents will also be 
  157.     ; effected.  You can see that the event handler is installed here.
  158.     ; As events occur in the sub-components of the compound widgets,
  159.     ; the events are passed up the tree until they hit this base 
  160.     ; where the event handler you define above handles them.  Similarily
  161.     ; whenever WIDGET_CONTROL, SET/GET_VALUE is called on this base,
  162.     ; the routine defined by the FUNC_GET/PRO_SET_VALUE is called to
  163.     ; set the value of the compound widget.  None of the three keywords
  164.     ; that override the standard behaviour are not required so it 
  165.     ; depends on your usage whether they are needed.
  166.   mainbase = WIDGET_BASE(parent, UVALUE = uval, $
  167.         EVENT_FUNC = "tmpl_event", $
  168.         FUNC_GET_VALUE = "tmpl_get_value", $
  169.         PRO_SET_VALUE = "tmpl_set_value")
  170.  
  171.     ; Here you would define the sub-components of your widget.  There
  172.     ; is an example component which is just a label.
  173.   state.id = WIDGET_LABEL(mainbase, VALUE = "Compound Widget Template")
  174.  
  175.     ; Save out the initial state structure into the first childs UVALUE.
  176.   WIDGET_CONTROL, WIDGET_INFO(base, /CHILD), SET_UVALUE=state, /NO_COPY
  177.  
  178.     ; Return the base ID of your compound widget.  This returned
  179.     ; value is all the user will know about the internal structure
  180.     ; of your widget.
  181.   RETURN, mainbase
  182.  
  183. END
  184.  
  185.  
  186.  
  187.  
  188.  
  189.